Format Specification Syntax: scanf and wscanf functions

The information here applies to the entire scanf family of functions, including the secure versions and describes the symbols used to tell the scanf functions how to parse the input stream into values that are inserted into program variables.

scanf reads all characters in stdin up to the first whitespace character (space, tab, or newline), or the first character that cannot be converted according to format; this is the input field.

The format string is read from left to right. A whitespace character in format causes scanf to read, but not store, all consecutive whitespace characters in the input field up to the next nonwhitespace character. A nonwhitespace character in format causes scanf to read, but not store, all matching characters. A format specification causes scanf to read and convert applicable characters in the input field into values of a particular type, to be stored in the optional arguments as they are read from stdin.

Format specifications always have a preceding percent sign (%) followed by a format-control character. Additional optional format-control characters may also appear. If % is followed by a character that has no meaning as a format-control character, that character and these characters (up to the next %) are treated as an ordinary sequence of characters that is, a sequence of characters that must match the input. For example, to specify a percent-sign character to be input, use %%.

An asterisk (*) following the % suppresses storage of the next input field that is interpreted as a field of the specified type. The field is scanned but not stored.

If a character in stdin conflicts with the format specification, scanf terminates. The character is left in stdin as if it had not been read.

A format specification, which consists of optional and required fields, has this form:

%[*][width][{h|l|L|j|t|z}]type

The format argument specifies the interpretation of the input and can contain one or more of the following:

White-space characters: blank (' '); tab ('\t'); or newline ('\n'). A white-space character causes scanf to read, but not store, all consecutive white-space characters in the input up to the next non–white-space character. One white-space character in the format matches any number (including 0) and combination of white-space characters in the input.
Non–white-space characters, except for the percent sign (%). A non–white-space character causes scanf to read, but not store, a matching non–white-space character. If the next character in the input stream does not match, scanf terminates.
Format specifications, introduced by the percent sign (%). A format specification causes scanf to read and convert characters in the input into values of a specified type. The value is assigned to an argument in the argument list.

Each field of the format specification is a single character or number signifying a particular format option. The optional fields appear before the required type character. These are the fields in a scanf format specification:

Field Description

width A positive decimal integer controlling the maximum number of characters to be read from stdin. No more than width characters are converted and stored at the corresponding argument. Fewer than width characters may be read if a white-space character (space, tab, or newline) or a character that cannot be converted according to the given format occurs before width is reached.

h, l, L,j,t,z

Optional prefixes that determine the type required for the argument expected (l and h are ignored if specified for any other type), as shown below:

h	Used with the integer types `d`, `i`, `o`, `x`, and `X` to specify that the argument is short integer, or with `u` to specify short unsigned int. Used with c or C to specify that the argument is a single-byte character in both scanf and wscanf. Used with s or S to specify that the argument is a single-byte character string in both scanf and wscanf.
l	Used with `d`, `i`, `o`, `x`, and `X` type characters to specify that the argument is long integer, or with `u` to specify long unsigned integer; also used with `e`, `E`, `f`, `g`, and `G` types to specify double rather than float. If used with `%p`, it indicates a 32-bit pointer. Used with c or C to specify that the argument is a wide character in both scanf and wscanf. Used with s or S to specify that the argument is a wide character string in both scanf and wscanf.
`ll`, `L`, `I64`	Used with d, i, u, o, x and X types to specify a 64-bit integer.
L	Used with `d`, `I`, `o`, `x`, and `X` types to specify 64-bit integer, also used with `e`, `E`, `f`, `g`, and `G` types to specify long double.
j	Used with d, i, u, o, x and X types to specify a intmax_t value.
t	Used to specify a ptrdiff_t value.
z	Used to specify a size_t value.

type Required character that determines the required type for the associated argument.

Type field characters

These are the type characters and their meanings:

Character	Input type expected	Argument type
`d`	Decimal integer	Pointer to integer.
`o, O`	Octal integer	Pointer to integer.
`x`	Hex integer	Pointer to integer. Since the input for %x format specifier is always interpreted as a hexadecimal number, the input should not include a leading 0x. (If 0x is included, the 0 is interpreted as a hexadecimal input value.)
`i`	Decimal, hexadecimal, or octal integer	Pointer to integer.
`u`	Unsigned decimal integer	Pointer to unsigned integer.
`U`	Unsigned decimal integer	Pointer to unsigned integer.
`e`, `E`, `f`, `g`	Double. Value consisting of an optional sign (+ or -), a series of one or more digits containing a decimal point, and an optional exponent (e or E) followed by an optionally signed integer value. Pointer to double.	Pointer to double.
`c`	Character. When used with scanf functions, specifies single-byte character; when used with wscanf functions, specifies wide character. Whitespace characters that are ordinarily skipped are read when `c` is specified; to read the next nonwhitespace character, use %1s.	Pointer to `char` when used with `scanf` functions, pointer to `wchar_t` when used with `wscanf` functions.
`C`	Opposite size character. When used with scanf functions, specifies wide character; when used with wscanf functions, specifies single-byte character. White-space characters that are ordinarily skipped are read when C is specified. To read next non–white-space single-byte character, use %1s.	Pointer to wchar_t when used with scanf functions, pointer to char when used with wscanf functions.
`s`	String	Pointer to character array large enough for input field plus a terminating null character \0, which is automatically appended.
`n`	No input read.	Pointer to int, into which the number of characters successfully read is stored.
`p`	Address in a form dependent on the memory model, `yyyyyyyy`, which is <32-bit offset>.	Pointer to pointer to void.

The number of fields converted and assigned, which may be less than the number requested. Does not include fields that were read but not assigned.

EOF if the end-of-file is encountered in the first attempt to read a character.